home *** CD-ROM | disk | FTP | other *** search
/ EnigmA Amiga Run 1996 June / EnigmA AMIGA RUN 08 (1996)(G.R. Edizioni)(IT)[!][issue 1996-06][EARSAN CD VII].iso / earcd / comm2 / xraid123.lha / DOC / XScan.doc < prev   
Text File  |  1995-08-27  |  19KB  |  452 lines
  1.                XScan - Generic Packet Scanner for the Amiga
  2.        Copyright (c) 1995 by Robert Williamson, FIDONET#1:167/104.0
  3.                             ALL RIGHTS RESERVED
  4.  
  5.         This  software  is  provided  "as  is",  without warranty and/or
  6.     guarantee  of any kind.  You may use and/or distribute this software
  7.     and copies of it, as long as no alterations have been made, no files
  8.     have  been  added  to/omitted from the original distribution archive
  9.     and no charge is asked for.
  10.         This package may be freely distributed via BBSs, ADS, AmiNet and
  11.     software libraries such as Fred Fish's and Aminet CD-ROMs, and other
  12.     similar electronic channels.
  13.         This package may NOT be distributed by SAN or by Disk magazines,
  14.     PD  libraries  or  BBSs  and  Services  that  charge  extra for file
  15.     transfers  without  authorization  from,  and  compensation  to  the
  16.     author.
  17.  
  18.   What is XScan?
  19.     XScan  is  a packet scanner which reads packets and creates a formatted
  20.   output  of  all  messages  found that are addressed to one the configured
  21.   Robot programs or aliases.
  22.  
  23.     Robot  is  a  generic term used to describe classes of programs such as
  24.   Area  Managers,  File Forwarders and FileFind programs.  By providing for
  25.   configurable  output formats, parameter expansion, aliases and formatting
  26.   of  both message body and subject line style area manager commands, XScan
  27.   removes  the  need  for  packet  scanning code within Robots.  XScan also
  28.   permits  complete  independance  from  the  local message base format and
  29.   removes  the  need  for  multiple  passes on the same packet for multiple
  30.   Robot programs.
  31.  
  32.     XScan  was  designed  to  meet  my  needs and those of my own software,
  33.   including  the XRaid fileecho area manager, the AreaMGR echo area manager
  34.   and  the  FQuery  FileFind  program.   However, it has been designed in a
  35.   manner  that  will hopefully make it useful for other Robot programs that
  36.   can read a list.
  37.  
  38.   Status of This Release:
  39.     This  is  BETA  and  given the great number of features it probably has
  40.   bugs.  In the case of a serious ERROR, and if the error conditions allow,
  41.   the  error  message  will  be logged.  Please forward this information to
  42.   myself at either:
  43.                FIDONET#1:167/104.0 or AMIGANET#40:600/104.0.
  44.  
  45.     BE  SURE  that you have set these addresses as ROUTED in your tosser or
  46.   packer/router config , so as not to incure long-distance charges.
  47.  
  48.     The  LogLevel  for  log messages is presently set quite low in order to
  49.   display  a  lot  of progress info for debugging.  At a LOGLEVEL of 3, the
  50.   log  will  grow very fast.  At a later date, loglevels will be changed to
  51.   insure a minimal amount of info for normal processing.
  52.  
  53.     This  documentation may not be always up to date, as features are being
  54.   added  at  a  very quick pace.  Refer to the example XSCAN.cfg for config
  55.   changes and the XSCAN usage display for command line changes.
  56.  
  57.     The  ToDo  list  is  changed  daily, items being either implemented and
  58.   removed  from  the list or new items added.  There is no obligation on my
  59.   part to implement anything in the ToDO list unless a contract to do so is
  60.   entered into by myself and a customer.
  61.  
  62.   Copyrights:
  63.     XSCAN, XSCAN.doc and the format of XSCAN.cfg are all,
  64.        Copyright (c) 1995 by Robert Williamson, FIDONET#1:167/104.0
  65.  
  66.   Why did I write it?
  67.     Simply  because  I  found  that  my  system  was getting much too busy,
  68.   scanning  each  packet  over  and  over for messages to XRAID, FQUERY and
  69.   other  Robots as well as scanning my netmail directories on every import.
  70.   XScan allows me the luxury of scanning my packets ONLY ONCE and permitted
  71.   me to drop the Robot scanning code from my NetMGR.
  72.  
  73.   Requirements:
  74.     WB 2.1 MINIMUM
  75.     rexxdossupport.library v2.3
  76.     The AmigaOS command Protect must be either resident or on the path.
  77.  
  78.     XScan  uses  a  STACK  of  64K  (yup..buffered  i/o  ON the stack) when
  79.     scanning  packets.   It  restores  the  stack to original value when it
  80.     exits.  
  81.  
  82.     XScan sets the Archive bit on each packet it scans.
  83.  
  84.   Features:
  85.     o pure, residentable
  86.     o multi-ftn
  87.     o independant of tosser and message base type
  88.     o handles both netmail and echomail
  89.     o configurable robot names, aliases, output format
  90.     o extensive parameter substitution 
  91.     o does not modify the packets
  92.  
  93.   Installation:
  94.     Be  sure that your dearc command preserves attributes.  If it does not,
  95.   run:
  96.     > Protect Mail:XSCAN pwerd
  97.  
  98.     Copy  XScan  to  somewhere  on  your  path, MAIL:  is nice.  For faster
  99.   loading, you can pre-load it as resident with these commands:
  100.     > Resident Mail:XScan ADD
  101.  
  102.     Make  sure  you  REMOVE  or  REPLACE  the  old  resident  version  when
  103.   upgrading and that you do not have any other program called XScan on your
  104.   path.
  105.  
  106.     If  you do not have a CFG:  assign, create one and place your XScan.CFG
  107.   there.   Otherwise,  you  will  have  to  specify  the  CFG  path  on the
  108.   commandline.   If  you are going to do it anyways, then a good idea is to
  109.   copy the config to RAM:  in your startup and use
  110.           CFG RAM:XScan.CFG 
  111.   in your XScan command lines.  This will speed up operations as bit more.
  112.  
  113.     Copy  rexxdossupport.library  and rexxplslib.library to any directory of
  114.   your LIBS:  assign.
  115.  
  116.    Copy  Start-ARexx  to  S:.   Then  remove  the call to RexxMast in your
  117.   S:Startup-Sequence and add a call to S:Start-ARexx to your S:User-Startup.
  118.   
  119.     Copy RPStart#? to your SYS:WBstartup directory. 
  120.  
  121.  
  122.   When to Scan packets:
  123.     Packet  scanning  can  be  done a number of ways.  Whichever method you
  124.   choose,  it  is  your  responsibiity  to  insure you do not scan the same
  125.   packet more than once.
  126.     The  BEST  way to run XSCAN (or any packet scanner, for that matter) is
  127.   from  a  CRON,  once  a  day, just before midnight, from a directory that
  128.   contains backups of all packets received.
  129.   
  130.       Run >NIL: XScan SCANDIR $(indir) AGE 0
  131.  
  132.     This  is  how I do it.  My tossing software allows me to backup packets
  133.   before tossing, even those within archives, and trim the backups by age.
  134.  
  135.     Another  method  would  be to export all mail to a dummy point and scan
  136.   those packets.  This method is inefficient and a waste of disk space.
  137.  
  138.     An  alternate  method  would  be  to scan each packet BEFORE importing.
  139.   While  this  is  trivial for packets received, when dealing with ArcMail,
  140.   this method would require one of:
  141.       -  a tosser that allows you to configure a command to execute between
  142.          de-arcing and tossing
  143.       -  modification of your dearc command to call XSCAN before returning
  144.          to the tosser
  145.       -  some other trick you may come up with :) 
  146.   
  147.  
  148.   Templates: 
  149.     XScan  uses standard AmigaDos Templates for both command line arguments
  150.   and  for  many  configuration  items.   See  the  example  XSCAN.CFG  for
  151.   explanation of templates used in the config file.
  152.  
  153.   Command Line Usage:
  154.     The  various  modes  allows  use  of  XScan in WhenRecd, TurnAround and
  155.   AfterSession  commands as well as in a cli.  The template is divided into
  156.   functional sets.  A Set is defined by the first or base parameter.
  157.  
  158.     DEBUG,  LOGLEVEL  and  CFG may be used with any set, but may not be the
  159.   last  items in the command line if a /F template is specified in the set.
  160.   Template  parameters  that  are  not  valid for the set are ignored.  The
  161.   template below shows each Set.
  162.  
  163.  
  164.  
  165. Template:
  166.   CFG/K,LOGLEVEL/K,SHOWCFG/S,DEBUG/S,NOEXE/S,XLATE/S
  167.   SCANDIR/K,AGE/K,PKTS/K/F
  168.  
  169.  Commands
  170.    SHOWCFG [CFG file] [LOGLEVEL level] [DEBUG]
  171.               Displays configuration
  172.  
  173.    SCANDIR directory [AGE day] [CFG file] [LOGLEVEL level] [DEBUG] [FORCE]
  174.               directory is scanned for all PKTs less or equal to AGE
  175.  
  176.    [CFG file] [LOGLEVEL level] [DEBUG] [FORCE] PKTS filename...filename 
  177.               the specified PKTs are scanned
  178.  Modifiers
  179.    AGE        number of days, the maximum age of packets to scan
  180.               Default is 0 for packets received today, maximum is 30.
  181.               Applies only to SCANDIR.
  182.  
  183.    FORCE      forces rescanning of already scanned packets 
  184.               Applies only to SCANDIR and PKTS
  185.  
  186.    XLATE      If XLATE is specified on the command line, AreaFix/Raid
  187.               dash-style command found in the subject are translated to
  188.               AreaMGR %-style commands. 
  189.  
  190.    CFG        fullpathname of config file
  191.               Default is CFG:XSCAN.CFG
  192.  
  193.    LOGLEVEL   Overides configured default and scan program loglevels
  194.               level must be between 0 and 9
  195.  
  196.    DEBUG      extremely verbose mode, also forces loglevel to 9
  197.  
  198.    NOEXE      Disables execution of EXE ad REXXMSG commands.
  199.               This applies to SCANDIR and PKTS.  Use this switch to perform
  200.               a scan and list to debug your ECHOFMT and NETFMT parameters.
  201.  
  202.  examples
  203.  
  204.    XScan CFG cfg:FQ.cfg PKTS audit:35656187.pkt inbound:12567736.pkt
  205.  
  206.    XScan SCANDIR Mail:Inbound AGE 2
  207.  
  208.    XScan SHOWCFG CFG CFG:XScan.cfg
  209.  
  210.    XScan NOEXE DEBUG PKTS t:test.pkt
  211.  
  212.   Configuration:
  213.     See example XSCAN.CFG
  214.  
  215.   Addressing:
  216.     Addresses  can  be specified in a number of formats in the config file,
  217.   the preferred being FQFA.  The minimum acceptable is 3d (z:net/node.) for
  218.   FidoNet  and FTNS listed in FTNLIST.  All other FTNs must be specified as
  219.   5D or FQFA.
  220.  
  221.         Address Formats:
  222.             FQFA  -   ftn#zone:net/node.point   (all must be present)
  223.             5d    -   zone:net/node[.point]@ftn (if no point, 0 is assumed)
  224.             4d    -   zone:net/node.point
  225.             3d    -   zone:net/node
  226.  
  227.  
  228.   The LIST output file:
  229.     This  is  the  file  created  for  each program (SCAN in the config) on
  230.   behalf  of  which we are scanning the packets.  The file is always opened
  231.   in  APPEND  mode.  It is the responsibility of the SCAN program to delete
  232.   the  LIST  file  when it has completed processing it.  The format of each
  233.   line  is  defined for  each SCAN name by the keywords NETFMT, ECHOFMT and
  234.   AMCMDSEP.  The maximum length of an output line is 64K.
  235.  
  236.   
  237.   Parameter Expansion:
  238.     Parameter  expansion  can  be  used  in the configuration items NETFMT,
  239.   ECHOFMT, EXE and REXXMSG. Not ethat for the last two, you are limited by
  240.   the  256  character  command line limit.  Parameter which upon expansion,
  241.   exceed this will be truncated by amigados.
  242.  
  243.     Each expandable parameter is enclosed in «..» double-brakets (ALT-9 and
  244.   ALT-0).   These may appear as 1/2 and top-left-corner, depending upon the
  245.   font you are using.
  246.  
  247.                             General Parameters
  248.                             ------------------
  249.   «pgm»         name of this program
  250.   «tv»          copyright text of this program
  251.   «sv»          version of this program
  252.   «vv»          VERS: string of this program
  253.  
  254.  
  255.                              Packet Parameters
  256.                              -----------------
  257.   «packet»      fullpathname of packet file
  258.   «pktlen»      length of packet in bytes
  259.  
  260.  
  261.                    Parameters derived from Packet Header
  262.                    -------------------------------------
  263.   «pktdate»     date of creation of packet
  264.                 format: dd.mm.yyyy" "hh:mm:ss
  265.   «prodlo»      ftsc product code of packet creation program (lo)
  266.   «prodhi»      ftsc product code of packet creation program (hi)
  267.   «prodver»     version and revision of packet creation program
  268.   «prodname»    Name of packet creation program (requires PRODFILE)
  269.   «prodtype»    Type of packet creation program (requires PRODFILE)
  270.   «prodos»      OS  of packet creation program (requires PRODFILE)
  271.   «prodby»      Author of packet creation program (requires PRODFILE)
  272.   «prodadr»     Contact address of packet creation program author
  273.                 (requires PRODFILE)
  274.  
  275.   «fromsite»    FQFA of sender of packet
  276.                 Note that for echomail and routed netmail, this is the
  277.                 address of your HUB.
  278.   «oftn»        FTN of packet sender 
  279.   «ozone»       ZONE of packet sender
  280.   «onet»        NET of packet sender
  281.   «onode»       NODE of packet sender
  282.   «opoint»      POINT of packet sender
  283.  
  284.   «tosite»      FQFA of packet destination
  285.   «dftn»        FTN of packet destination
  286.   «dzone»       ZONE of packet destination
  287.   «dnet»        NET of packet destination
  288.   «dnode»       NODE of packet destination
  289.   «dpoint»      POINT of packet destination
  290.   
  291.  
  292.                Parameters derived from Packed Message Header
  293.                ---------------------------------------------
  294.   «toadr»       message net/node destination address
  295.   «toname»      message to name
  296.         
  297.   «fromadr»     message net/node originating address
  298.                 Note that in the case of echomail, this is your ECHOHUB,
  299.                 not the originator of the message.
  300.   «fromname»    message from name
  301.  
  302.   «subject»     message subject
  303.   «msgdate»     message date
  304.   «cost»        cost of message
  305.  
  306.   «abits»       attribute word in binary (16 bits)
  307.   «attrtext»    attribute word as space-separated text string
  308.                 
  309.                 Bit   0 Priv
  310.                 Bit   1 Crash
  311.                 Bit   2 Recd
  312.                 Bit   3 Sent
  313.                 Bit   4 Fatt
  314.                 Bit   5 InTransit
  315.                 Bit   6 Orphan
  316.                 Bit   7 KillSent
  317.                 Bit   8 Local
  318.                 Bit   9 HoldForPickup
  319.                 Bit  10 Tracked
  320.                 Bit  11 FReq
  321.                 Bit  12 ReceiptReq
  322.                 Bit  13 IsReceipt
  323.                 Bit  14 AuditReq
  324.                 Bit  15 UpdateReq
  325.  
  326.  
  327.               Parameters derived from Body of Packed Message
  328.               ----------------------------------------------
  329.  
  330.   «msgtext»     Contents of message excluding control lines, Origin and
  331.                 Seen-Bys.  CR is converted to soft-return (0x8d hex)
  332.  
  333.   «intl»        INTL control line contents (excludes control field name)
  334.                 XScan recognizes this kludge both with and without a colon
  335.   «fmpt»        FMPT control line contents (excludes control field name)
  336.                 XScan recognizes this kludge both with and without a colon
  337.   «topt»        TOPT control line contents (excludes control field name)
  338.                 XScan recognizes this kludge both with and without a colon
  339.   «msgid»       MSGID control line contents (excludes control field name)
  340.   «pid»         PID  control line contents (excludes control field name)
  341.   «via»         VIA control line contents (excludes control field name)
  342.                 This is the LAST via in message.
  343.  
  344.   «tagname»     AREA TAGNAME (excludes control field name)
  345.   «origin»      ORIGIN control line contents (excludes control field name)
  346.   «morg»        address as listed in ORIGIN control line
  347.  
  348.  
  349.  
  350.      Parameters derived from the config for detected SCAN program name
  351.      -----------------------------------------------------------------
  352.   «scanprog»    program name
  353.   «ECHOAREAS»   echomail areas to be scanned
  354.   «ECHOALIAS»   echomail aliases for program
  355.   «NETALIAS»    netmail aliases for program
  356.   «list»        fullpathname of the output listing for this SCAN
  357.   «adrfmt»      obsolete
  358.   «logfile»     currently selected LOGFILE
  359.   «loglevel»    currently selected LOGLEVEL
  360.  
  361.  
  362.   «exe»         command to execute may be used in the output list
  363.                 in order to create an EXECUTE script.
  364.                 eg:NETFMT «exe» «dst3d»|«fromname»|«subject»|«org5d»|«amcmds»
  365.  
  366.  
  367.                           Constructed parameters
  368.                           ----------------------
  369.   «mtime»       time message was processed
  370.   «mdate»       date message was processed
  371.  
  372.   «toprog»      name of program to which message is addressed
  373.                 This is the first word of «toname») returned as UPPERCASE
  374.  
  375.   «password»    This is only applicable to NETMAIL
  376.                 This is the first word of «subject» returned as UPPERCASE
  377.  
  378.   «afcmds»      This is only applicable to NETMAIL
  379.                 AreaFix/Raid type commands from SUBJECT of message, case is
  380.                 NOT changed.
  381.  
  382.   «amcmds»      This is only applicable to NETMAIL
  383.                 A  list  of FSC57-style AreaMGR commands that were found in
  384.                 the  body  of  the  message.   Each  is  separated with the
  385.                 defined  AMCMDSEP.   These  commands include all lines that
  386.                 begin with '+', '-' or '%'.
  387.  
  388.   «xlcmds»      If XLATE is specified on the command line, AreaFix/Raid
  389.                 dash-style command fun inthe subject line are translated to
  390.                 AreaMGR %-style commands. This variable is the translated
  391.                 commands.
  392.  
  393.   «cline»       The number of FSC57-style AreaMGR command lines that were
  394.                 found in the  body  of  the  message.
  395.  
  396.   «FAFQorg»     origin address
  397.   «org5d»       
  398.   «org3d»
  399.   «odm»         FTN of originator (uppercase)
  400.   «ozn»         zone  of originator
  401.   «ont»         net of originator
  402.   «ond»         node of originator
  403.   «opt»         point of originator
  404.  
  405.   «fqfadst»     destination address (ususally our own)
  406.   «dst5d»
  407.   «dst3d»
  408.   «ddm»         FTN of destination (uppercase)
  409.   «dzn»         zone  of destination
  410.   «dnt»         net of destination
  411.   «dnd»         node of destination
  412.   «dpt»         point of destination
  413.  
  414.  
  415.                         Additional Developer Notes
  416.  
  417.   There  are  many  other  undocumented  expansion parameters.  Ask and you
  418.   shall receive :)
  419.  
  420.  
  421.   Address Expansion:
  422.     «fqfadst»  and  «fqfaorg» are constructed FQFA addresses, using FTNLIST
  423.   to build a FQFA.  (Fully Qualified FTN Address) The 3d and 5d versions of
  424.   org and dst (org3d,org5d,dst3d,dst5d) are derived from the FQFA versions.
  425.   For both 3d and 5d, the point number is not included if zero.
  426.  
  427.     The FTNLIST in XSCAN.cfg is used for address expansion.  The address is
  428.   determined by checking the packed message fields in the following order.
  429.  
  430.     If  an  INTL  kludge is present then the origin address and destination
  431.   addresses of that kludge is used.  A check must be made for TOPT and FMPT
  432.   also,  and the point number appended to the appropriate address if either
  433.   is found.
  434.  
  435.     If  there  is no INTL control line and an ORIGIN control line is found,
  436.   the address in the Origin (morg) is used to build the originating fqfa.
  437.  
  438.     If  there  is  neither  INTL  nor  ORIGIN, and the address in the MSGID
  439.   control line is an FTN address, it shall be used for the origin address.
  440.  
  441.     If  the FTN of the msgid is not an FTN address, the destination address
  442.   is set using our HOST AKA that is in the same FTN as the originator. If a
  443.   REPLY  control  line exists, the address therin is used to build the FQFA
  444.   destination.
  445.  
  446.     If  the FTN of the msgid is not an FTN address, the destination address
  447.   is set using our HOST AKA that is in the same FTN as the originator.
  448.     
  449.  
  450.  
  451.  --more to come--
  452.